tmf-prepay-balance-management-biz
POST AdjustBalance
URL
https://[localhost]:[port]/tmf-api/prepayBalanceManagement/v4/{businessId}/adjustBalance
URL PARAMS
name | type | description | required |
---|---|---|---|
businessId | string | 2 letter ISO 3166 country code (TT, BB, JM, PA, etc.) identifying the business unit. | Y |
Header
name | value | description | required |
---|---|---|---|
client_id | string | Public identifier to the application o channel | Y |
client_secret | string | Is a secret known only to the application and the authorization server | Y |
X-Correlation-ID | string | Identifier that correlates HTTP request between a client and server. Any identification model (UUDI, checksum, etc.) can be used, as long as it is a unique value to differentiate a transaction. | Y |
Request Body for PA
{
"adjustType": "credit",
"reason": "SK2.0",
"amount": {
"amount": 2,
"units": "USD"
},
"logicalResource": [
{
"id": "65554122"
}
],
"characteristic": [
{
"name": "AdjustmentCode",
"value": "CP"
},
{
"name": "TotalAmount",
"value": "3"
},
{
"name": "AmountPaid",
"value": "0.2"
},
{
"name": "transactionId",
"value": "344849"
}
],
"@type": "Adelanta Saldo"
}
Definitions
Skipped properties: id,href,status,requestedDate,confirmationDate,relatedParty,partyAccount
name | type | description | required |
---|---|---|---|
description | string | Description of the recharge operation | N |
reason | string | Text describing the reason for the action/task | N |
adjustType | AdjustType | Valid values are RecurringCharge or OneTimeCharge | Y |
amount | Quantity | Indicate the amount on the bucket | Y |
amount.amount | number | Numeric value in a given unit | |
amount.units | string | Unit of measurement for the numeric value | |
amount.'@baseType' | string | When sub-classing, this defines the super-class | |
amount.'@schemaLocation' | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
amount.'@type' | string | When sub-classing, this defines the sub-class entity name | |
bucket | BucketRef [] | A reference to the bucket impacted by the request or value | Y |
bucket[].id | string | unique identifier | Y |
bucket[].href | string | Hyperlink reference | N |
bucket[].name | string | Name of the related entity. | N |
bucket[].'@baseType' | string | When sub-classing, this defines the super-class. Example value: ResourceSpecification | N |
bucket[].'@schemaLocation' | string (uri) | A URI to a JSON-Schema file that defines additional attributes and relationships. Example value: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json | N |
bucket[].'@type' | string | When sub-classing, this defines the sub-class Extensible name. Example value: LogicalResourceSpecification | N |
bucket[].'@referredType' | string | The actual type of the target instance when needed for disambiguation. | N |
channel | ChannelRef | Indicator for the channel used to request the transfer | N |
channel.id | string | Unique identifier | Y |
href | string | Hyperlink reference | N |
channel.name | string | Name of the channel | N |
channel.'@baseType' | string | When sub-classing, this defines the super-class | N |
channel.'@schemaLocation' | string (uri) | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
channel.'@type' | string | When sub-classing, this defines the sub-class Extensible name | N |
channel.'@referredType' | string | The actual type of the target instance when needed for disambiguation | N |
logicalResource | LogicalResourceRef [] | The logical resource related to the operation | N |
logicalResource[].id | string | Unique identifier | Y |
logicalResource[].href | string | Hyperlink reference | N |
logicalResource[].name | string | Name of the related entity | N |
logicalResource[].'@baseType' | string | When sub-classing, this defines the super-class | N |
logicalResource[].'@schemaLocation' | string (uri) | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
logicalResource[].'@type' | string | When sub-classing, this defines the sub-class Extensible name | N |
logicalResource[].'@referredType' | string | The actual type of the target instance when needed for disambiguation | N |
product | ProductRef [] | The products related to the operation | N |
product[].id | string | Unique identifier of the product | Y |
product[].href | string | Hyperlink reference to the product | N |
product[].name | string | Name of the related product entity | N |
product[].'@baseType' | string | Defines the super-class when sub-classing | N |
product[].'@schemaLocation' | string | URI to a JSON-Schema file that defines additional attributes and relationships | N |
product[].'@type' | string | Defines the sub-class Extensible name when sub-classing | N |
product[].'@referredType' | string | The actual type of the target instance when needed for disambiguation | N |
requestor | RelatedParty | Identifier for the user/customer/entity that performs the top-up action | N |
requestor.id | string | Unique identifier | Y |
requestor.href | string | Hyperlink reference | N |
requestor.name | string | Name of the related entity | N |
requestor.role | string | Role played by the related party | N |
requestor.'@baseType' | string | When sub-classing, this defines the super-class | N |
requestor.'@schemaLocation' | string | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
requestor.'@type' | string | When sub-classing, this defines the sub-class Extensible name | N |
requestor.'@referredType' | string | The actual type of the target instance when needed for disambiguation | Y |
usageType | string/enum | Valid values for the usage type are [ monetary, voice, data, sms, other ] | Y |
validFor | TimePeriod | The period for which the balance in the bucket is valid | N |
validFor.endDateTime | string | End of the time period, using IETC-RFC-3339 format | No |
validFor.startDateTime | string | Start of the time period, using IETC-RFC-3339 format. | No |
validFor.'@baseType' | string | When sub-classing, this defines the super-class | No |
validFor.'@schemaLocation' | string | A URI to a JSON-Schema file that defines additional attributes and relationships | No |
validFor.'@type' | string | When sub-classing, this defines the sub-class entity name | No |
'@baseType' | string | When sub-classing, this defines the super-class | N |
'@schemaLocation' | string (URI) | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
'@type' | string | When sub-classing, this defines the sub-class entity name | N |
Response
In this section all the possible data structures received by the client at the moment of responding the method are defined.
Possible response success
This section defines all the possible data structures received by the client and that must be considered satisfactory at the time of responding to the method.
[ 201 ] for PA
{
"logicalResource": {
"id": "65554122",
"@type": "MSISDN",
"@baseType": "logicalResource"
},
"amount": {
"units": "USD",
"amount": 2.0
}
}
Definitions
name | type | description | required |
---|---|---|---|
id | string | Unique Identifier for the resource | N |
href | string | A reference to the resource | N |
confirmationDate | string | Date when the deduction was confirmed in the server | N |
description | string | Description of the recharge operation | N |
reason | string | Text describing the reason for the action/task | N |
requestedDate | string | Date when the deduction request was received in the server | N |
adjustType | AdjustType | Valid values are RecurringCharge or OneTimeCharge | Y |
amount | Quantity | Indicate the amount on the bucket | Y |
amount.amount | number | Numeric value in a given unit | |
amount.units | string | Unit of measurement for the numeric value | |
amount.'@baseType' | string | When sub-classing, this defines the super-class | |
amount.'@schemaLocation' | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
amount.'@type' | string | When sub-classing, this defines the sub-class entity name | |
bucket | BucketRef [] | A reference to the bucket impacted by the request or value | Y |
bucket[].id | string | unique identifier | Y |
bucket[].href | string | Hyperlink reference | N |
bucket[].name | string | Name of the related entity. | N |
bucket[].'@baseType' | string | When sub-classing, this defines the super-class. Example value: ResourceSpecification | N |
bucket[].'@schemaLocation' | string (uri) | A URI to a JSON-Schema file that defines additional attributes and relationships. Example value: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json | N |
bucket[].'@type' | string | When sub-classing, this defines the sub-class Extensible name. Example value: LogicalResourceSpecification | N |
bucket[].'@referredType' | string | The actual type of the target instance when needed for disambiguation. | N |
channel | ChannelRef | Indicator for the channel used to request the transfer | N |
channel.id | string | Unique identifier | Y |
href | string | Hyperlink reference | N |
channel.name | string | Name of the channel | N |
channel.'@baseType' | string | When sub-classing, this defines the super-class | N |
channel.'@schemaLocation' | string (uri) | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
channel.'@type' | string | When sub-classing, this defines the sub-class Extensible name | N |
channel.'@referredType' | string | The actual type of the target instance when needed for disambiguation | N |
logicalResource | LogicalResourceRef [] | The logical resource related to the operation | N |
logicalResource[].id | string | Unique identifier | Y |
logicalResource[].href | string | Hyperlink reference | N |
logicalResource[].name | string | Name of the related entity | N |
logicalResource[].'@baseType' | string | When sub-classing, this defines the super-class | N |
logicalResource[].'@schemaLocation' | string (uri) | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
logicalResource[].'@type' | string | When sub-classing, this defines the sub-class Extensible name | N |
logicalResource[].'@referredType' | string | The actual type of the target instance when needed for disambiguation | N |
partyAccount | PartyAccountRef | PartyAccount reference. A party account is an arrangement that a party has with an enterprise that provides products to the party. | N |
partyAccount.id | string | Unique identifier of the party account | Y |
partyAccount.href | string | Reference of the party account | N |
partyAccount.description | string | Detailed description of the party account | N |
partyAccount.name | string | Name of the party account | N |
partyAccount.status | string | The condition of the account, such as due, paid, in arrears. | N |
partyAccount.'@baseType' | string | When sub-classing, this defines the super-class | N |
partyAccount.'@schemaLocation' | string | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
partyAccount.'@type' | string | When sub-classing, this defines the sub-class entity name | N |
partyAccount.'@referredType' | string | The actual type of the target instance when needed for disambiguation. | N |
product | ProductRef [] | The products related to the operation | N |
product[].id | string | Unique identifier of the product | Y |
product[].href | string | Hyperlink reference to the product | N |
product[].name | string | Name of the related product entity | N |
product[].'@baseType' | string | Defines the super-class when sub-classing | N |
product[].'@schemaLocation' | string | URI to a JSON-Schema file that defines additional attributes and relationships | N |
product[].'@type' | string | Defines the sub-class Extensible name when sub-classing | N |
product[].'@referredType' | string | The actual type of the target instance when needed for disambiguation | N |
relatedParty | RelatedParty [] | Used to provide information about any other entity with relation to the operation | N |
RelatedParty[].relatedParty | array | Used to provide information about any other entity with relation to the operation. Each element of the array should follow the structure defined in the RelatedParty definition. | N |
RelatedParty[].requestor | object | Identifier for the user/customer/entity that performs the top-up action. This can be used to indicate the identifier of an agent that performs the operation on behalf of a user via a customer service channel. Structure including at least attributes role and name. It should follow the structure defined in the RelatedParty definition. | N |
RelatedParty[].status | string | Status of the operation. It should follow the structure defined in the ActionStatusType definition. | N |
RelatedParty[].usageType | string | Defines the type of the underlying balance, such as data, voice, or any currency such as EUR or USD, etc. It should follow the structure defined in the UsageType definition. | N |
RelatedParty[].validFor | object | The period for which the balance in the bucket is valid. It should follow the structure defined in the TimePeriod definition. | N |
RelatedParty[].'@baseType' | string | When sub-classing, this defines the super-class. | N |
RelatedParty[].'@schemaLocation' | string | A URI to a JSON-Schema file that defines additional attributes and relationships. | N |
RelatedParty[].'@type' | string | When sub-classing, this defines the sub-class entity name. | N |
requestor | RelatedParty | Identifier for the user/customer/entity that performs the top-up action | N |
requestor.id | string | Unique identifier | Y |
requestor.href | string | Hyperlink reference | N |
requestor.name | string | Name of the related entity | N |
requestor.role | string | Role played by the related party | N |
requestor.'@baseType' | string | When sub-classing, this defines the super-class | N |
requestor.'@schemaLocation' | string | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
requestor.'@type' | string | When sub-classing, this defines the sub-class Extensible name | N |
requestor.'@referredType' | string | The actual type of the target instance when needed for disambiguation | Y |
usageType | string/enum | Valid values for the usage type are [ monetary, voice, data, sms, other ] | Y |
validFor | TimePeriod | The period for which the balance in the bucket is valid | N |
validFor.endDateTime | string | End of the time period, using IETC-RFC-3339 format | N |
validFor.startDateTime | string | Start of the time period, using IETC-RFC-3339 format. | N |
validFor.'@baseType' | string | When sub-classing, this defines the super-class | N |
validFor.'@schemaLocation' | string | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
validFor.'@type' | string | When sub-classing, this defines the sub-class entity name | N |
'@baseType' | string | When sub-classing, this defines the super-class | N |
'@schemaLocation' | string (URI) | A URI to a JSON-Schema file that defines additional attributes and relationships | N |
'@type' | string | When sub-classing, this defines the sub-class entity name | N |
Possible response error
In this section all the possible data structures received by the client are defined and that must be considered as unsatisfactory when responding to the method.
[ 400 ]
Bad Request - the request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
{
"errors" : [{
"code" : 400,
"message" : "OCS:ERROR_CODE",
"description" : "Error description."
}]
}
[ 404 ]
Not Found - server has not found a resource with that URI. This may be temporary and permanent condition. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.
{
"errors" : [{
"code": 404
"message": "SUBSCRIBER_NOT_FOUND"
"description": "Subscriber not found"
}]
}
[ 500 ]
Internal Server Error - server encountered an error processing request. This should not happen normally, but it is a generic error message, given when no more specific message is suitable.
{
errors: [{
code: 500,
description: "OCS:ERROR",
message: "Other Error"
}]
}
[ 501 ]
Not implemented - indicates that the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.
{
"errors" : [{
"code" : 501,
"message" : "Not implemented",
"description" : "Operation POST /adjustBalance for Business Id: xxxx not implemented"
}]
}